3.0 Programming

> 3.1 Function Reference

> libagbir.a is the IR communication library. Make sure you include the 'AgbIr.h' header file. The IR communication library, libagbir.a, has the functions required for IR communication. The processing for each function is as follows:

> void irBegin( u16 tmrno, irResult* IrResultStr, u8 wait)
> Call this function at the beginning of IR communication. It internally backs up the IE, IME and timer control register for the timer "tmrno" in addition to the content of each register for the setup values. (By calling the function, irEnd, the back-up content is restored. The Interrupt Master Enable flag register (IME) is disabled to prohibit all interrupts. (If not, communication cannot be performed.)
> In order to synchronize communication, the timer for the argument tmrno is set up to run. If a 1 is passed to the wait flag, wait, there is a delay of at least 2ms before communication is possible.

> void irRamCopy ( u32* Ram_S_Buf, u32* Ram_R_Buf)
> The core communication program for transmitting and receiving data (ARM code) is transferred to the buffer.
> Make sure you set aside the following for the buffer in the CPU internal RAM which is 32 bit aligned:
> Required word size for send buffer (Ram_S_Buf): IR_ARM_SEND_CORE_SIZE
> Required word size for receive buffer (Ram_R_Buf): IR_ARM_RECV_CORE_SIZE

> void irMountArmCore( u32* Ram_S_Buf, u32* Ram_R_Buf)
> The send/receive buffer addresses for the communication core program are the arguments. The communication core program in RAM is used for communication. Make sure that you copy the core program with the function irRamCopy before calling this function.

> void irMountThumbCore( void)
> The communication core program in the ROM is used (ROM version) for the communication after calling this function.

> void irInit( void)
> Initializes the communication status. Please call this function once before each data transfer.

> u8 irSendConnect( u16 bps)
> Sends a connection request as the transmitting side to the other machine. Using the argument, bps, determine the communication speed. (See "1.2 Communication Speed".) Sets up the registers IE, IME, timer control, and the setting values. After the connection request has been sent, this function returns IR_SUCCESS if the receiving side sends a normal connection reply. Otherwise, IR_FAILURE is returned.

> u8 irRecvConnect( u16 bps)
> Sends a connection reply as the receiving side to the other machine. Using the argument, bps, determine the communication speed. (See "1.2 Communication Speed") Sets up the registers IE, IME, timer control, and the setting values.
> If there was a normal connection request, this function sends a connection reply and returns IR_SUCCESS. Otherwise, IR_FAILURE is returned.

> u8 irSendPacket( u16* addr, u8 halfwords)
> This function sends the header + data + checksum and then receives the status. Using the argument, addr, specify the send data starting address and set the transmission data number in half-words.
> If communication proceeds normally, IR_SUCCESS is returned. Otherwise, IR_FAILURE is returned. Up to 255 half-words can be transmitted with one call of this function. If more data is needed, this function must be called more than once.

> u8 irRecvPacket( u16* addr, u8 halfwords)
> This function receives the header + data + checksum and then sends the status. Using the argument, addr, specify the receive data starting address and set the transmission data number in half-words.
> If communication proceeds normally, IR_SUCCESS is returned. Otherwise, IR_FAILURE is returned. Up to 255 half-words can be received with one call of this function. If more data is needed, this function must be called more than once.

> void irDisconnect( void)
> This function terminates IR communication while on standby. Restore the registers IE, IME, timer control, and setting values from the buffer which are saved when the function irBegin is called.
> Communication is restarted with irSendConnect or irRecvConnect. If you are interrupting communication for a long time, use the irEnd function in order to reduce the power consumption.

> void irEnd( void)
> Call this function at the end of the IR communication. Stop the timer. Returns the content of IE, IME, timer control and the setting values, which are saved when the function irBegin is called. Also, this function operates the R register and shuts down the IR adapter.

> irResult structure
> This structure stores various kinds of information for IR communication. Please keep it in the CPU internal RAM. The state of communication can be obtained by referencing this information. The communication library uses this structure, so be careful not to write to the structure's members. This may disrupt normal communication.
> typedef struct {
> u8 halfwords;
> u8 mode;
> u16 status;
> u16 sum;
> }irResult;
> halfwords: Contains the number of bytes being transmitted or received.
> mode: Contains the constant that indicates whether the connection is to the transmitting side or to the receiving side.
> status: Contains the communication status.
> sum: Contains the checksum value.

> 3.2 Flowcharts

> The most basic communication procedure is shown below:

> When using the RAM to carry out high speed communication, replace irMountThumbCore with irRamCopy and irMountArmCore.

> In actual communication, the transfer of data does not start immediately upon connection, but only after an exchange of key codes and other procedures. This is done in order to prevent erroneous communication between different games. See the flowchart shown below:

> The key code processing can involve such procedures as bit inversion, swapping upper and lower 8bits, doing an arithmetic operation or a logic operation with a certain constant, or performing a combination of these.

> It is possible to temporarily halt communication using irDisconnect to perform another process. Don't perform another process until irSendConnect has completed. The flowchart below shows this process: